@vascend/talos 0.1.0

package/README.md

@@ -0,0 +1,202 @@
+<p align="center">
+  <img src="assets/branding/talos-hero.png" alt="Vascend Talos" width="880">
+</p>
+
+<h1 align="center">Vascend Talos</h1>
+
+<p align="center"><strong>Your models. Your tools. Your coding workflow.</strong><br>
+An extensible coding agent runtime for the terminal and the applications you build.</p>
+
+<p align="center">
+  <a href="package.json"><img src="https://img.shields.io/badge/version-0.1.0-c5a55a?style=flat-square" alt="v0.1.0"></a>
+  <a href="https://bun.sh"><img src="https://img.shields.io/badge/runtime-Bun-171717?style=flat-square&amp;logo=bun&amp;logoColor=white" alt="Bun"></a>
+  <a href="src/sdk.ts"><img src="https://img.shields.io/badge/TypeScript-CLI_%2B_SDK-3178c6?style=flat-square&amp;logo=typescript&amp;logoColor=white" alt="TypeScript CLI + SDK"></a>
+  <img src="https://img.shields.io/badge/Windows_%7C_macOS_%7C_Linux-555555?style=flat-square" alt="Windows, macOS, Linux">
+</p>
+
+<p align="center"><strong>English</strong> · <a href="readme/README.it.md">Italiano</a> · <a href="readme/README.es.md">Español</a> · <a href="readme/README.de.md">Deutsch</a></p>
+
+<p align="center">
+  <a href="#quick-start">Quick start</a> · <a href="#why-talos">Features</a> · <a href="#cli--sdk">CLI &amp; SDK</a> · <a href="docs/README.md">Documentation</a> · <a href="https://github.com/VascendTechnologies/vascend-talos/issues">Issues</a>
+</p>
+
+---
+
+**Talos brings the agent loop, tools and session context into one runtime.** Work in your terminal, automate a task from a script, or embed the same engine in an application. Choose your provider, resume a conversation and extend the workflow with skills and MCP tools.
+
+Talos also powers **Vascend Horizon**. The standalone CLI runs independently of the desktop application.
+
+## Quick start
+
+Install [Node.js 20 or newer](https://nodejs.org), then run:
+
+```bash
+npm install -g @vascend/talos
+talos
+```
+
+You can also use `bun add -g @vascend/talos`, `pnpm add -g @vascend/talos`, or `yarn global add @vascend/talos` (Yarn Classic).
+The package includes the compiled CLI and SDK; GitHub access and a local build are not required.
+
+On macOS and Linux, the installer uses a writable user directory:
+
+```bash
+curl -fsSL https://cdn.jsdelivr.net/npm/@vascend/talos@latest/install.sh | bash
+```
+
+On Windows, run in PowerShell:
+
+```powershell
+irm https://cdn.jsdelivr.net/npm/@vascend/talos@latest/install.ps1 | iex
+```
+
+Both installers require Node.js 20+ and npm. Run `talos` to check for newer stable versions;
+the startup prompt shows `current version → new version` and offers **Skip for now** or **Update now**.
+
+On first launch, follow the Vascend account sign-in flow. Use `/login` to configure provider access and `/models` to choose a model. Then give Talos a task:
+
+```text
+Explain this repository, identify its entry points, and suggest where to add tests.
+```
+
+<details>
+<summary><strong>Run from source or update your installation</strong></summary>
+
+For a source checkout, install [Git](https://git-scm.com/downloads) and [Bun](https://bun.sh), then use a GitHub account with repository access:
+
+```bash
+git clone https://github.com/VascendTechnologies/vascend-talos.git
+cd vascend-talos
+bun install --frozen-lockfile
+bun run install:cli
+```
+
+For development, run `bun run dev` from the repository. For a single task:
+
+```bash
+bun run src/index.ts -p "Summarize this repository"
+```
+
+To update a clean checkout and rebuild the global commands:
+
+```bash
+git pull --ff-only
+bun install --frozen-lockfile
+bun run install:cli
+```
+
+Full configuration and API key examples: [CLI reference](docs/CLI-REFERENCE.it.md#avvio-dal-sorgente) (Italian).
+
+</details>
+
+## Why Talos
+
+| Capability | What it gives you |
+| --- | --- |
+| **One engine, multiple interfaces** | Interactive CLI, one-shot tasks, JSONL RPC, a TypeScript SDK and Horizon Engine. |
+| **Provider choice** | Anthropic, OpenAI-compatible providers and local Ollama models, with a model picker inside the session. |
+| **Resumable work** | Saved conversations, session branches, context inspection and project memory. |
+| **Extensible tools** | File and shell tools, MCP connections, skills, hooks and project instructions. |
+| **A readable terminal** | Compact operation previews, full details on demand and questions that leave your draft intact. |
+| **Explicit control** | Configurable permissions, separate desktop consent and teams started on request. |
+
+## Keep your place in the conversation
+
+**Keep writing while the agent asks a question.** Questions wait above the prompt. Open one when you are ready, choose an option or select **Other** to write your own answer. Your main prompt and answer drafts remain separate.
+
+| Action | Shortcut |
+| --- | --- |
+| Open a pending question | **Shift+←** |
+| Submit an answer | **Enter** |
+| Return to the main prompt and keep the answer draft | **Alt+↓** or **Esc** |
+| Skip the current question | **Ctrl+]** |
+| Read complete tool output | **Ctrl+R** |
+| Manage queued messages | **Alt+Q** or `/queue` |
+
+Loaded skills have a compact activity entry; the full content stays in the operation details:
+
+```text
+• Explored
+  └ Read SKILL.md (vascend-ops skill)
+```
+
+Use `/language` to choose **English, Italian, Spanish or German**. The choice is saved between launches. `/language system` restores automatic detection; `TALOS_LANGUAGE` provides a process-level override.
+
+## CLI & SDK
+
+| Entry point | Example | Use |
+| --- | --- | --- |
+| Interactive terminal | `talos` | Work alongside the agent. |
+| One-shot execution | `talos -p "Explain this project"` | Scripts, pipes and individual tasks; add `--json` for events. |
+| RPC | `talos --rpc` | Connect a host over stdin/stdout using JSONL. |
+| TypeScript SDK | `import { bootstrap, runTurn } from "@vascend/talos"` | Embed the agent loop in a process. |
+| Horizon Engine | `HorizonEngine.create(...)` | Integrate the headless engine with an application. |
+
+The SDK import is the package entry point after building and linking or installing the repository. See the [SDK exports](src/sdk.ts) and [architecture](docs/ARCHITECTURE.md).
+
+### Everyday commands
+
+| Command | Purpose |
+| --- | --- |
+| `/help` | Browse available commands. |
+| `/login` · `/models` | Configure provider access and select a model. |
+| `/new` · `/resume` | Start a conversation or reopen a saved one. |
+| `/context` · `/usage` | Inspect context and provider usage. |
+| `/todo` · `/collaboratori` | Inspect the plan or explicitly start collaborators. |
+| `/queue` · `/language` | Manage pending messages and the interface language. |
+
+## Providers and extensions
+
+Use **Anthropic, OpenAI, OpenRouter, Mistral, DeepSeek, xAI, Together, MiniMax or Ollama**, or configure a compatible endpoint. Available models and authentication methods depend on the provider and your account. See the [provider catalog](src/providers/catalog.ts).
+
+- **Project instructions:** define working rules in `AGENTS.md` and `SYSTEM.md`.
+- **Skills:** load reusable instructions from `SKILL.md`, including `/skill:name` invocations.
+- **MCP:** connect external tools through the shared tool protocol.
+- **Extensions:** add tools, commands, hooks and templates to the runtime.
+
+The package declares no production npm dependencies. Optional integrations and desktop control can require additional system programs.
+
+## Platforms
+
+| Platform | CLI | Desktop control |
+| --- | --- | --- |
+| Windows | Supported | Standalone backend included. |
+| macOS | Supported | Requires `cliclick` and Accessibility / Screen Recording permissions. |
+| Linux | Supported | X11 requires `xdotool` and ImageMagick. Global Wayland control is not supported. |
+
+Desktop control requires separate consent, including when automatic tool approvals are enabled. See [Computer Use](docs/COMPUTER-USE.md) for setup and limitations.
+
+## Documentation
+
+| Guide | Contents |
+| --- | --- |
+| [Documentation index](docs/README.md) | Find the right guide. |
+| [CLI reference](docs/CLI-REFERENCE.it.md) | Installation, commands, configuration, queues and providers. |
+| [Architecture](docs/ARCHITECTURE.md) | Runtime modules and integration boundaries. |
+| [Computer Use](docs/COMPUTER-USE.md) | Desktop backends, permissions and setup. |
+| [Context Fabric](docs/CONTEXT-FABRIC.md) | Context management and retrieval. |
+| [Tool protocol](docs/TOOL-PROTOCOL.md) | Tool discovery and execution. |
+| [Benchmarks](bench/README.md) | Evaluation suites and how to run them. |
+
+This README is available in four languages. The extended technical guides are currently primarily in Italian.
+
+## Development
+
+```bash
+bun run typecheck
+bun run typecheck:bench
+bun run test:unit
+bun run build
+```
+
+Unit test files run in separate processes. For one suite: `bun run test:unit -- test/queued-questions.test.ts`. See the [E2E documentation](test/e2e/README.md) for integration test setup.
+
+Report bugs in [Issues](https://github.com/VascendTechnologies/vascend-talos/issues) with your platform, Bun version, reproduction steps and relevant logs, with credentials removed.
+
+## Project and license
+
+Built by [Vascend Technologies](https://vascend.it). Inspired by the extensible agent philosophy of [Pi](https://pi.dev).
+
+The package is marked **`UNLICENSED`**. This repository does not grant an open-source license; use and distribution require permission from Vascend Technologies.
+
+<p align="center"><strong>English</strong> · <a href="readme/README.it.md">Italiano</a> · <a href="readme/README.es.md">Español</a> · <a href="readme/README.de.md">Deutsch</a> · <a href="docs/README.md">Documentation</a></p>

package/dist/backend/asset-events.d.ts

@@ -0,0 +1,31 @@
+import { type RoomRecord } from "../vascend/room-memory.js";
+import type { Asset } from "./types.js";
+export type AssetEventType = "asset.uploaded" | "asset.linked" | "asset.analyzed" | "asset.versioned";
+export interface AssetEvent {
+    readonly type: AssetEventType;
+    readonly asset: Asset;
+    readonly taskId?: string;
+    readonly relation?: string;
+    readonly analysis?: string;
+    readonly version?: string;
+    readonly note?: string;
+    readonly at: number;
+}
+export interface AssetEventSink {
+    emit(event: AssetEvent): void;
+}
+export declare function formatAssetEventRecord(room: string, event: AssetEvent): RoomRecord;
+export declare class RoomMemoryAssetSink implements AssetEventSink {
+    private readonly sessionDir;
+    private readonly storeId;
+    private readonly namespace;
+    private constructor();
+    static open(sessionDir: string, storeId: string, namespace?: string): RoomMemoryAssetSink;
+    emit(event: AssetEvent): void;
+}
+export declare class InMemoryAssetSink implements AssetEventSink {
+    private readonly events;
+    emit(event: AssetEvent): void;
+    all(): readonly AssetEvent[];
+    ofType(type: AssetEventType): readonly AssetEvent[];
+}

package/dist/backend/asset-events.js

@@ -0,0 +1,149 @@
+// Dominio EVENTI ASSET: collega l'AssetStore alla memoria delle stanze
+// (RoomMemory, metodo Danilov) generando eventi di memoria per ogni file,
+// immagine, documento o allegato. Ogni operazione produce un evento del
+// dominio "assets.*":
+//
+//   asset.uploaded  — un asset e' stato caricato (create)
+//   asset.linked    — un asset e' stato collegato a un task/entita'
+//   asset.analyzed  — un asset e' stato analizzato (estrazione/OCR/sintesi)
+//   asset.versioned — una nuova versione di un asset e' stata registrata
+//
+// Ogni evento viene INDICIZZATO come stanza (RoomRecord livello 0) cosi' da
+// essere richiamabile via il tool `recall` (ricerca per termini o per id).
+// Filosofia del progetto: zero dipendenze a runtime, immutabilita', il sink e'
+// una primitiva iniettabile (non una feature hardcoded nello store).
+import { RoomMemory } from "../vascend/room-memory.js";
+// Etichetta umana breve del tipo evento (per titolo/azione Danilov).
+function actionLabel(type) {
+    switch (type) {
+        case "asset.uploaded": return "caricato";
+        case "asset.linked": return "collegato";
+        case "asset.analyzed": return "analizzato";
+        case "asset.versioned": return "versionato";
+    }
+}
+// Tokenizza un valore in termini utili all'indice (>=2 char, no rumore base).
+// Indicizza sia il token "intero" (es. "bilancio-2024.csv") sia le sue
+// sotto-parole separate da -, ., _, / (es. "bilancio", "2024", "csv") cosi'
+// l'asset e' richiamabile via recall anche cercando una sola parola del nome.
+function terms(...values) {
+    const out = new Set();
+    const add = (raw) => {
+        const t = raw.replace(/^[^a-z0-9]+|[^a-z0-9]+$/g, "");
+        if (t.length >= 2)
+            out.add(t);
+    };
+    for (const v of values) {
+        if (!v)
+            continue;
+        for (const whole of v.toLowerCase().match(/[a-z0-9_./-]{2,}/g) ?? []) {
+            add(whole);
+            for (const part of whole.split(/[-._/]+/))
+                add(part);
+        }
+    }
+    return [...out].filter((t) => t.length >= 2);
+}
+function escapeValue(value) {
+    return value.replace(/\s+/g, " ").trim().replace(/"/g, "'");
+}
+// Costruisce il RoomRecord Danilov di un evento asset (stanza livello 0).
+// `room` e' l'id assegnato dallo store (namespaced, es. "asset-R1"). Il body
+// e' un blocco INDICE/DEFINIZIONI/RELAZIONI/OUTPUT, coerente col resto della
+// memoria, cosi' la ricerca BM25 di RoomMemory lo trova per termini.
+export function formatAssetEventRecord(room, event) {
+    const { type, asset } = event;
+    const action = actionLabel(type);
+    const title = `${type}: ${asset.name} (${asset.kind})`;
+    const indexTerms = [
+        ...terms(asset.name, asset.kind, asset.mime, type.replace("asset.", "")),
+        ...terms(asset.visionId, event.taskId, event.relation, event.version),
+        ...terms(asset.description, event.analysis, event.note),
+        "asset",
+        action,
+    ];
+    const uniqTerms = [...new Set(indexTerms)].filter(Boolean).slice(0, 24);
+    const def = [
+        `@evento[${room}]: type=${type}, action=${action}, at=${event.at}`,
+        `@asset[${asset.id}]: name="${escapeValue(asset.name)}", kind=${asset.kind}, mime=${asset.mime}, size=${asset.size}`,
+        `@vision[${asset.visionId}]: proprietario_logico`,
+    ];
+    if (event.taskId) {
+        def.push(`@task[${event.taskId}]: relazione=${event.relation ?? "appartiene"}`);
+    }
+    if (event.analysis) {
+        def.push(`@analisi[${room}]: "${escapeValue(event.analysis).slice(0, 600)}"`);
+    }
+    if (event.version) {
+        def.push(`@versione[${room}]: ${escapeValue(event.version)}`);
+    }
+    if (asset.description) {
+        def.push(`@descrizione[${asset.id}]: "${escapeValue(asset.description).slice(0, 400)}"`);
+    }
+    if (event.note) {
+        def.push(`@nota[${room}]: "${escapeValue(event.note).slice(0, 400)}"`);
+    }
+    const target = event.taskId ? `task:${event.taskId}` : `vision:${asset.visionId}`;
+    const rel = `@R: ${room} -> ${type} -> asset:${asset.id} -> ${target}  [ ${action} ]`;
+    const body = `INDICE
+${uniqTerms.map((t, i) => `${i + 1} = ${t}`).join("\n")}
+
+DEFINIZIONI
+${def.join("\n")}
+
+RELAZIONI
+${rel}
+
+OUTPUT: asset ${asset.id} "${escapeValue(asset.name)}" ${action}${event.taskId ? ` e collegato a ${event.taskId}` : ""}; richiamabile via recall.`;
+    return {
+        room,
+        level: 0,
+        title: escapeValue(title).slice(0, 160),
+        terms: uniqTerms,
+        body,
+        children: [],
+        parent: null,
+        createdAt: event.at,
+    };
+}
+// Sink concreto su RoomMemory: indicizza ogni evento come stanza richiamabile
+// via recall. Usa il namespace "asset" per gli id (asset-R1, asset-R2, ...)
+// cosi' gli eventi asset non collidono con le stanze conversazionali e sono
+// filtrabili. Non lancia mai: in caso d'errore inghiotte (best-effort).
+export class RoomMemoryAssetSink {
+    sessionDir;
+    storeId;
+    namespace;
+    constructor(sessionDir, storeId, namespace) {
+        this.sessionDir = sessionDir;
+        this.storeId = storeId;
+        this.namespace = namespace;
+    }
+    // `storeId` e' l'id dello store stanze (sessionId o id regno in Kingdoms).
+    static open(sessionDir, storeId, namespace = "asset") {
+        return new RoomMemoryAssetSink(sessionDir, storeId, namespace);
+    }
+    emit(event) {
+        try {
+            const mem = RoomMemory.open(this.sessionDir, this.storeId);
+            const room = mem.nextRoomId(this.namespace);
+            mem.append(formatAssetEventRecord(room, event));
+        }
+        catch {
+            // L'indicizzazione e' best-effort: non deve rompere l'operazione asset.
+        }
+    }
+}
+// Sink in-memory per i test/uso programmatico: tiene gli eventi e li espone.
+export class InMemoryAssetSink {
+    events = [];
+    emit(event) {
+        this.events.push(event);
+    }
+    all() {
+        return this.events;
+    }
+    ofType(type) {
+        return this.events.filter((e) => e.type === type);
+    }
+}

package/dist/backend/assets.d.ts

@@ -0,0 +1,31 @@
+import { type Asset, type AssetKind } from "./types.js";
+import type { AssetEventSink } from "./asset-events.js";
+export interface CreateAssetInput {
+    readonly kind: AssetKind;
+    readonly name: string;
+    readonly mime?: string;
+    readonly data?: Buffer;
+    readonly snippet?: string;
+    readonly description?: string;
+}
+export declare class AssetStore {
+    private readonly file;
+    private readonly blobDir;
+    private readonly sink?;
+    private readonly byId;
+    private readonly versions;
+    private constructor();
+    static open(dataDir: string, sink?: AssetEventSink): AssetStore;
+    create(visionId: string, userId: string, input: CreateAssetInput, taskId?: string): Asset;
+    linkToTask(id: string, userId: string, taskId: string, relation?: string): Asset;
+    recordAnalysis(id: string, userId: string, analysis: string, taskId?: string): Asset;
+    addVersion(id: string, userId: string, version: string, note?: string): Asset;
+    versionsOf(id: string, userId: string): readonly string[];
+    listFor(visionId: string, userId: string): Asset[];
+    require(id: string, userId: string): Asset;
+    readBlob(id: string, userId: string): Buffer;
+    delete(id: string, userId: string): void;
+    private blobPath;
+    private persist;
+    private emit;
+}

package/dist/backend/assets.js

@@ -0,0 +1,210 @@
+// Store degli asset di esempio associati a una Vision: i METADATI vivono su un
+// file JSONL append-only (assets.jsonl), mentre il CONTENUTO binario degli
+// asset image/file vive in blob separati su filesystem (assets/blobs/<id>).
+// Gli asset di tipo "snippet" hanno il contenuto inline nei metadati e nessun
+// blob. Stesso stile di ConversationStore. Zero dipendenze a runtime.
+import { appendFileSync, mkdirSync, readFileSync, writeFileSync, existsSync, rmSync, } from "node:fs";
+import { join } from "node:path";
+import { newId } from "./crypto.js";
+import { HttpError } from "./types.js";
+function isDelete(e) {
+    return e.op === "delete";
+}
+// Limite di dimensione per un singolo blob (10 MB): sono asset DI ESEMPIO.
+const MAX_BLOB_BYTES = 10 * 1024 * 1024;
+// Limite per il contenuto inline di uno snippet (256 KB).
+const MAX_SNIPPET_BYTES = 256 * 1024;
+export class AssetStore {
+    file;
+    blobDir;
+    sink;
+    byId = new Map();
+    // Versioni registrate per asset (asset.versioned): id -> elenco versioni.
+    versions = new Map();
+    constructor(file, blobDir, 
+    // Sink opzionale degli eventi di memoria (asset.*). Iniettabile: lo store
+    // resta una primitiva e non dipende da RoomMemory. Se assente, nessun
+    // evento viene emesso (retro-compatibile).
+    sink) {
+        this.file = file;
+        this.blobDir = blobDir;
+        this.sink = sink;
+    }
+    // `sink` opzionale: se passato, ogni operazione emette un evento di memoria
+    // (asset.uploaded/linked/analyzed/versioned) indicizzato e richiamabile via
+    // recall. Tipicamente RoomMemoryAssetSink.open(sessionDir, sessionId).
+    static open(dataDir, sink) {
+        const assetsDir = join(dataDir, "assets");
+        const blobDir = join(assetsDir, "blobs");
+        mkdirSync(blobDir, { recursive: true });
+        const store = new AssetStore(join(assetsDir, "assets.jsonl"), blobDir, sink);
+        if (existsSync(store.file)) {
+            const raw = readFileSync(store.file, "utf8");
+            for (const line of raw.split("\n")) {
+                if (!line.trim())
+                    continue;
+                try {
+                    const e = JSON.parse(line);
+                    if (isDelete(e))
+                        store.byId.delete(e.id);
+                    else
+                        store.byId.set(e.id, stripOp(e));
+                }
+                catch { /* riga corrotta: ignora */ }
+            }
+        }
+        return store;
+    }
+    // Crea un asset per una Vision. Per image/file salva il blob su disco; per
+    // snippet salva il contenuto inline. Ritorna i metadati persistiti. Emette
+    // l'evento di memoria asset.uploaded (e, se `taskId`, lo collega al task).
+    create(visionId, userId, input, taskId) {
+        const name = input.name.trim();
+        if (!name)
+            throw new HttpError(400, "nome asset mancante", "invalid_field");
+        if (!visionId.trim())
+            throw new HttpError(400, "visionId mancante", "invalid_field");
+        const id = newId("asset");
+        const now = Date.now();
+        if (input.kind === "snippet") {
+            const snippet = input.snippet ?? "";
+            if (Buffer.byteLength(snippet, "utf8") > MAX_SNIPPET_BYTES) {
+                throw new HttpError(413, "snippet troppo grande", "payload_too_large");
+            }
+            const asset = {
+                id,
+                visionId,
+                userId,
+                kind: "snippet",
+                name: name.slice(0, 200),
+                mime: input.mime ?? "text/plain",
+                size: Buffer.byteLength(snippet, "utf8"),
+                snippet,
+                ...(input.description ? { description: input.description.slice(0, 1000) } : {}),
+                createdAt: now,
+            };
+            this.persist(asset);
+            this.emit("asset.uploaded", asset, now, taskId ? { taskId, relation: "appartiene" } : {});
+            return asset;
+        }
+        const data = input.data ?? Buffer.alloc(0);
+        if (data.length > MAX_BLOB_BYTES) {
+            throw new HttpError(413, "asset troppo grande", "payload_too_large");
+        }
+        writeFileSync(this.blobPath(id), data);
+        const asset = {
+            id,
+            visionId,
+            userId,
+            kind: input.kind,
+            name: name.slice(0, 200),
+            mime: input.mime ?? "application/octet-stream",
+            size: data.length,
+            ...(input.description ? { description: input.description.slice(0, 1000) } : {}),
+            createdAt: now,
+        };
+        this.persist(asset);
+        this.emit("asset.uploaded", asset, now, taskId ? { taskId, relation: "appartiene" } : {});
+        return asset;
+    }
+    // Collega un asset a un task (o entita'). Emette asset.linked: l'asset
+    // diventa richiamabile via recall in relazione al task di appartenenza.
+    linkToTask(id, userId, taskId, relation = "allegato") {
+        const asset = this.require(id, userId);
+        if (!taskId.trim())
+            throw new HttpError(400, "taskId mancante", "invalid_field");
+        this.emit("asset.linked", asset, Date.now(), { taskId, relation });
+        return asset;
+    }
+    // Registra l'esito di un'analisi su un asset (OCR, estrazione, sintesi, ...).
+    // Emette asset.analyzed con il testo dell'analisi indicizzato per recall.
+    recordAnalysis(id, userId, analysis, taskId) {
+        const asset = this.require(id, userId);
+        const text = analysis.trim();
+        if (!text)
+            throw new HttpError(400, "analisi vuota", "invalid_field");
+        this.emit("asset.analyzed", asset, Date.now(), {
+            analysis: text,
+            ...(taskId ? { taskId } : {}),
+        });
+        return asset;
+    }
+    // Registra una nuova versione di un asset (es. "v2", o un hash). Tiene la
+    // cronologia versioni in memoria ed emette asset.versioned.
+    addVersion(id, userId, version, note) {
+        const asset = this.require(id, userId);
+        const v = version.trim();
+        if (!v)
+            throw new HttpError(400, "versione mancante", "invalid_field");
+        const list = this.versions.get(id) ?? [];
+        this.versions.set(id, [...list, v]);
+        this.emit("asset.versioned", asset, Date.now(), { version: v, ...(note ? { note } : {}) });
+        return asset;
+    }
+    // Versioni registrate per un asset (in ordine di registrazione).
+    versionsOf(id, userId) {
+        this.require(id, userId);
+        return this.versions.get(id) ?? [];
+    }
+    // Asset di una Vision (verificando la proprieta'), dal piu' recente.
+    listFor(visionId, userId) {
+        return [...this.byId.values()]
+            .filter((a) => a.visionId === visionId && a.userId === userId)
+            // Dal piu' recente; a parita' di timestamp ordine deterministico per id.
+            .sort((a, b) => b.createdAt - a.createdAt || (a.id < b.id ? 1 : a.id > b.id ? -1 : 0));
+    }
+    // Recupera i metadati assicurando che l'asset appartenga all'utente.
+    require(id, userId) {
+        const asset = this.byId.get(id);
+        if (!asset)
+            throw new HttpError(404, "asset non trovato", "not_found");
+        if (asset.userId !== userId)
+            throw new HttpError(403, "accesso negato", "forbidden");
+        return asset;
+    }
+    // Legge il blob binario di un asset image/file. Errore per gli snippet.
+    readBlob(id, userId) {
+        const asset = this.require(id, userId);
+        if (asset.kind === "snippet") {
+            throw new HttpError(400, "lo snippet non ha un blob: usa i metadati", "no_blob");
+        }
+        const path = this.blobPath(id);
+        if (!existsSync(path))
+            throw new HttpError(404, "blob non trovato", "not_found");
+        return readFileSync(path);
+    }
+    delete(id, userId) {
+        const asset = this.require(id, userId);
+        this.byId.delete(id);
+        if (asset.kind !== "snippet") {
+            const path = this.blobPath(id);
+            if (existsSync(path))
+                rmSync(path, { force: true });
+        }
+        appendFileSync(this.file, JSON.stringify({ op: "delete", id }) + "\n", "utf8");
+    }
+    blobPath(id) {
+        return join(this.blobDir, id);
+    }
+    persist(asset) {
+        this.byId.set(asset.id, asset);
+        appendFileSync(this.file, JSON.stringify({ ...asset, op: "upsert" }) + "\n", "utf8");
+    }
+    // Emette un evento di memoria sul sink, se presente. NON bloccante e non
+    // lancia: l'indicizzazione e' best-effort e non deve rompere l'operazione.
+    emit(type, asset, at, extra) {
+        if (!this.sink)
+            return;
+        try {
+            this.sink.emit({ type, asset, at, ...extra });
+        }
+        catch {
+            // best-effort: ignora gli errori del sink
+        }
+    }
+}
+function stripOp(e) {
+    const { op, ...asset } = e;
+    void op;
+    return asset;
+}

package/dist/backend/auth.d.ts

@@ -0,0 +1,18 @@
+import type { IncomingMessage } from "node:http";
+import type { UserStore } from "./users.js";
+import { type AuthResult, type AuthTokenPayload, type User } from "./types.js";
+import type { BackendConfig } from "./config.js";
+export declare class AuthService {
+    private readonly users;
+    private readonly config;
+    constructor(users: UserStore, config: BackendConfig);
+    register(email: string, password: string, displayName?: string): AuthResult;
+    login(email: string, password: string): AuthResult;
+    private issue;
+    resolve(token: string | undefined | null): {
+        payload: AuthTokenPayload;
+        user: User;
+    } | null;
+    static extractToken(req: IncomingMessage): string | null;
+    requireUser(req: IncomingMessage): User;
+}